<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html lang="en">
<HEAD>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> 

<TITLE>Extensible 3D (X3D), ISO/IEC FCD 19775-1r1:200x, 21 Key device sensor component</TITLE>
<link rel="stylesheet" href="../X3D.css" type="text/css">

</HEAD>
<BODY>

<div class="CenterDiv">
<IMG class="x3dlogo" SRC="../../Images/x3d.png" ALT="X3D logo" style="width: 176px; height: 88px"> 
</div>

<div class="CenterDiv">
<p class="HeadingPart">
    Extensible 3D (X3D)<br />
    Part 1: Architecture and base components</p>
<p class="HeadingClause">21 Key device sensor component</p>
</div>

<IMG class="x3dbar" SRC="../../Images/x3dbar.png" ALT="--- X3D separator bar ---" width="430" height="23">

<h1><a name="Introduction"></a>
<img class="cube" src="../../Images/cube.gif" alt="cube" width="20" height="19"> 
21.1 Introduction</h1>
<h2><a name="Name"></a>21.1.1 Name</h2>
<p>The name of this component is &quot;KeyDeviceSensor&quot;. This name shall be used when referring 
to this component in the COMPONENT statement (see
<a href="core.html#COMPONENTStatement">7.2.3.4 Component statement</a>).</p>
<h2><a name="Overview"></a>21.1.2 Overview</h2>

<p>This clause describes the Key Device Sensor component of this part of ISO/IEC 
19775. This includes how individual keystrokes and a series of keystrokes 
  are inserted into an X3D world. <a href="#t-Topics">Table 21.1</a> provides 
  links to the major topics in this clause.</p>

<div class="CenterDiv">

<p class="TableCaption">
<a name="t-Topics"></a><b>
Table 21.1 &#8212; Topics</b></p>

  <table>
    <tr> 
      <td> 
        <ul>
          <li><a href="#Introduction">21.1 Introduction</a>
            <ul>
              <li><a href="#Name">21.1.1 Name</a></li>
              <li><a href="#Overview">21.1.2 Overview</a></li>
            </ul></li>
          <li><a href="#Concepts">21.2 Concepts</a><li><a href="#Abstracttypes">21.3 Abstract types</a> 
            <ul>
              <li><a href="#X3DKeyDeviceSensorNode">21.3.1 <i>X3DKeyDeviceSensorNode</i></a></li>
            </ul></li>
          <li><a href="#Nodereference">21.4 Node reference</a> 
            <ul>
              <li><a href="#KeySensor">21.4.1 KeySensor</a></li>
              <li><a href="#StringSensor">21.4.2 StringSensor</a></li> 
            </ul></li>
          <li><a href="#SupportLevels">21.5 Support levels</a> 
        </ul>
        <ul>
          <li><a href="#t-Topics">Table 21.1 &#8212; Topics</a></li>
          <li><a href="#t-Actionkeyvalues">Table 21.2 &#8212; Action key values</a></li>
          <li><a href="#t-supportlevels">Table 21.3 &#8212; Key Device Sensor component support levels</a></li>
        </ul>
      </td>
    </tr>
  </table>
</div>

<h1><img class="cube" src="../../Images/cube.gif" alt="cube" width="20" height="19">
<a name="Concepts"></a>21.2 Concepts</h1>

<p>The following node types are keydevice sensors:</p>

<ul>
  <li><a href="#KeySensor">KeySensor</a></li> 
  <li><a href="#StringSensor">StringSensor</a></li> 
</ul>

<p>KeySensors generate an event whenever the state of a key associated with the 
  physical key device changes while the KeySensor is active. The identification 
  of the key whose state has changed is returned by the event.</p>

<p>StringSensors generate an event whenever the termination string specified for 
  the StringSensor is identified. The UTF-8 characters preceding the termination 
  string are returned by the event.&nbsp;StringSensors also generate interim events 
  whenever the string under construction changes. This allows prompting of the 
  string during construction.</p>

<p>One keyboard-style key device is assumed to be available either as a physical 
  device or through emulation whenever the sensor component is supported. For 
  a key device to generate input to a key device sensor, the key device shall 
  be active. Key devices are active when:</p>

<ol type="a">
  <li>The X3D world has focus in the supporting user interface; and</li>
  <li>The key device sensor has its <i>isActive</i> field set to <code>TRUE</code>.</li>
</ol>

<p>The <i>isActive</i> event generated by a change of the state of the <i>isActive</i> 
  field can be used for prompting.</p>

<p>A key device sensor is enabled when its <i>enabled</i> field is set to <code>TRUE</code>. 
  This causes the <i>isActive</i> field of the keydevice sensor to be set to <code>TRUE</code>. 
  Also, any other key device sensor which may be active will be sent an <i>enabled</i> 
  event with value <code>FALSE</code>. Only one key device 
  sensor may be active at a time</p>

<h1><img class="cube" src="../../Images/cube.gif" alt="cube" width="20" height="19">
<a name="Abstracttypes"></a>
21.3 Abstract types</h1>
<h2><a name="X3DKeyDeviceSensorNode"></a>
21.3.1 <i>X3DKeyDeviceSensorNode</i></h2>

<pre>X3DKeyDeviceSensorNode : X3DSensorNode {
  SFBool   [in,out] enabled  TRUE
  SFNode   [in,out] metadata NULL [X3DMetadataObject]
  SFBool   [out]    isActive         
}
</pre>

<p>This abstract node type is the base type for all sensor node 
    types that operate using key devices.</p>

<h1><img class="cube" src="../../Images/cube.gif" alt="cube" width="20" height="19">
<a name="Nodereference"></a>
21.4 Node reference</h1>

<h2><a name="KeySensor"></a>
21.4.1 KeySensor</h2>

<pre>KeySensor : X3DKeyDeviceSensorNode {
  SFBool   [in,out] enabled          TRUE
  SFNode   [in,out] metadata         NULL [X3DMetadataObject]
  SFInt32  [out]    actionKeyPress   
  SFInt32  [out]    actionKeyRelease 
  SFBool   [out]    altKey           
  SFBool   [out]    controlKey       
  SFBool   [out]    isActive         
  SFString [out]    keyPress         
  SFString [out]    keyRelease       
  SFBool   [out]    shiftKey         
}
</pre>

 <p>A KeySensor node generates events when the user presses keys 
    on the keyboard. A KeySensor node can be enabled or disabled by sending it an 
  <i>enabled</i> event with a value of <code>TRUE</code> or 
  <code>FALSE</code>. If the KeySensor node is disabled, 
  it does not track keyboard input or send events.</p>

  <p><i>keyPress</i> and <i>keyRelease</i> events are generated as 
    keys which produce characters are pressed and released on the keyboard. The 
    value of these events is a string of length 1 containing the single UTF-8 
    character associated with the key pressed. The set of UTF-8 characters that 
    can be generated will vary between different keyboards and different implementations.</p>

  <p><i>actionKeyPress</i> and <i>actionKeyRelease</i> events are 
    generated as 'action' keys are pressed and released on the keyboard. The value 
    of these events are in <a href="#t-Actionkeyvalues">Table 21.2</a>:</p>

<div class="CenterDiv">

<p class="TableCaption">
<a name="t-Actionkeyvalues"></a>
Table 21.2<b>
&#8212; </b>Action key values</p>

    <table>
      <tbody> 
      <tr> 
        <th>KEY</th>
        <th>VALUE</th>
        <th>KEY</th>
        <th>VALUE</th>
        <th>KEY</th>
        <th>VALUE</th>
      </tr>
      <tr> 
        <td>HOME</td>
        <td>13</td>
        <td>END</td>
        <td>14</td>
        <td>PGUP</td>
        <td>15</td>
      </tr>
      <tr> 
        <td>PGDN</td>
        <td>16</td>
        <td>UP</td>
        <td>17</td>
        <td>DOWN</td>
        <td>18</td>
      </tr>
      <tr> 
        <td>LEFT</td>
        <td>19</td>
        <td>RIGHT</td>
        <td>20</td>
        <td>F1-F12</td>
        <td>1-12</td>
      </tr>
      </tbody> 
    </table>
</div>

  <p><i>shiftKey</i>, <i>controlKey</i>, and <i>altKey</i> events are generated 
	as each of the shift, control, and alt keys on the keyboard is respectively 
	pressed and released. Their value is <code>TRUE</code> 
    when the key is pressed and <code>FALSE</code> when the 
    key is released.</p>

  <p>When a key is pressed, the KeySensor sends an <i>isActive</i> 
    event with value <code>TRUE</code>. Once the key is released, the
	KeySensor sends an <i>isActive</i> event with value <code>FALSE</code>.</p>

  <p>The KeySensor is not affected by its position in the transformation 
    hierarchy.</p>

  <p>Recommended default key mappings for navigation are described in
  <a href="../behaviours.html">Annex G Recommended navigation behaviours</a>.</p>

<h2><a name="StringSensor"></a>
21.4.2 StringSensor</h2>

<pre>StringSensor  : X3DKeyDeviceSensorNode {
  SFBool   [in,out] deletionAllowed TRUE
  SFBool   [in,out] enabled         TRUE
  SFNode   [in,out] metadata        NULL [X3DMetadataObject]
  SFString [out]    enteredText       
  SFString [out]    finalText         
  SFBool   [out]    isActive          
}
</pre>

<p>A StringSensor node generates events as the user presses keys on the 
keyboard.  A StringSensor node can be enabled or disabled by sending it an 
  <i>enabled</i> event with a value of <code>TRUE</code> or 
  <code>FALSE</code>. If the StringSensor node is disabled, 
  it does not track keyboard input or send events.</p>


  <p><i>enteredText</i> events are generated as keys which produce 
    characters are pressed on the keyboard. The value of this event is the UTF-8 
    string entered including the latest character struck. The set of UTF-8 characters 
    that can be generated will vary between different keyboards and different 
    implementations.  </p>


  <p>If a <i>deletionAllowed</i> has value <span class="code">TRUE</span>, the previously 
    entered character in the <i>enteredText</i> is removed when the 
  browser-recognized value for deleting the preceding character of a string is 
  entered. Typically, this value is defined by the local operating system. If <i>
  deletionAllowed</i> has value <span class="code">FALSE</span>, characters may only be added to the 
  string; deletion of characters shall not be allowed. Should the 
  browser-recognized value for deleting the preceding character is entered, it 
  shall be ignored.</p>

  <p>The <i>finalText</i> event is generated whenever the browser-recognized 
  value for terminating a string is entered. Typically, this value is defined by 
  the local operating system. When this recognition occurs, the 
    <i>finalText</i> field generates an event with value equal to that of <i>enteredText</i>. 
  After the 
    <i>finalText</i> field event has been generated, the <i>enteredText</i> 
  field is set to the empty string but no event is generated.</p>

  <p>When the user begins typing, the StringSensor sends an <i>isActive</i> 
    event with value <code>TRUE</code>. When the string
	is terminated, the StringSensor sends an <i>isActive</i> event with value <code>FALSE</code>.</p>

  <p>The StringSensor is not affected by its position in the transformation 
    hierarchy.</p>

<h1><img class="cube" src="../../Images/cube.gif" alt="cube" width="20" height="19">
<a name="SupportLevels"></a>21.5 Support levels</h1>

<p>The Key Device Sensor component provides 2 levels of support as specified 
  in <a href="#t-supportlevels">Table 21.3</a>. </p>

<div class="CenterDiv">

<p class="TableCaption">
<a name="t-supportlevels"></a>
Table 21.3<b>
&#8212; </b>Key device sensor component support levels</p>
  
<table>      <tr> 
        <th>Level</th>
        <th>Prerequisites</th>
        <th>Nodes/Features</th>
        <th>Support</th>
      </tr>
      <tr> 
        <td align="center"><b>1</b></td>
        <td> 
          Core 1
        </td>
        <td></td>
        <td></td>
      </tr>
      <tr> 
        <td align="center"></td>
        <td></td>
        <td><i>X3DKeyDeviceSensorNode </i>(abstract)</td>
        <td>n/a</td>
      </tr>
      <tr> 
        <td align="center"></td>
        <td></td>
        <td>KeySensor</td>
        <td>All fields fully supported.</td>
      </tr>
      <tr> 
        <td align="center"><b>2</b></td>
        <td>Core 1</td>
        <td></td>
        <td></td>
      </tr>
      <tr> 
        <td align="center"></td>
        <td></td>
        <td>All Level 1 Key Device Sensor nodes</td>
        <td>All fields as supported in Level 1.</td>
      </tr>
      <tr> 
        <td align="center"></td>
        <td></td>
        <td>StringSensor</td>
        <td>All fields fully supported.</td>
      </tr>
    </table>
  </div>

<img class="x3dbar" src="../../Images/x3dbar.png" alt="--- X3D separator bar ---" width="430" height="23" />

</body>
</html>